Callback Routine for Device Notification

The callback routine, callback routine parameter block, and callback notification request functions used for device notification are listed in this section.

The device notification mechanism is used to inform clients when devices are added and removed from the USB. Clients register for notification services using the USBInstallDeviceNotification function and can request all notifications or a specific notification type. Whenever a device or interface is added or removed from the bus, all registered clients are called back with the information about the device or interface.

Clients that register for notifications must be sure to un-register with the USBRemoveDeviceNotification function before their code fragment is unloaded.

The callback routine is always called at task time, and may allocate memory, make toolbox calls, or perform other system maintenance operations.

Device Notification Callback Routine

The device notification callback routine declaration is defined as:



 
typedef void (USBDeviceNotificationCallbackProc)

                    (USBDeviceNotificationParameterBlockPtr
pb);



 
typedef USBDeviceNotificationCallbackProc 

*USBDeviceNotificationCallbackProcPtr;

Device Notification Parameter Block

The parameter block for the device notification callback routine is defined as:



 
/* Device Notification Parameter Block */

struct USBDeviceNotificationParameterBlock

{

UInt16                               pbLength;

UInt16                               pbVersion;

USBNotificationType                  usbDeviceNotification;

UInt8                               reserved1;

USBDeviceRef                         usbDeviceRef;

UInt16                              usbClass;

UInt16                              usbSubClass;

UInt16                              usbProtocol;

UInt16                              usbVendor;

UInt16                              usbProduct;

OSStatus                            result;

UInt32                              token;

USBDeviceNotificationCallbackProcPtr
  callback;

UInt32                              refcon;

};

<--> usbDeviceNotification: The type of notification The following notifications are defined:kNotifyAnyEvent kNotifyAddDevice kNotifyAddInterface kNotifyRemoveDevice kNotifyRemoveInterface
<-- usbDeviceRef: The device reference for the target device
<--> usbClass: The class of the target device, use kUSBAnyClass for any class
<--> usbSubClass: The subclass of the target device, use kUSBAnySubClass for any subclass
<--> usbProtocol: The protocol of the target device, use kUSBAnyProtocol for any protocol
<--> usbVendor: The vendor ID of the target device, use kUSBAnyVendor for any vendor
<--> usbProduct: The product ID of the target device, use kUSBAnyProduct for any product
<-- result: The status of the call
<-- token: The identifier for this notification request
--> callback: A pointer to the callback routine to be called when the notification criteria is satisfied

Installing The Device Callback Request

The USBInstallDeviceNotification function installs the device notification routine for the device specified in the USBDeviceNotificationParameterBlock . Pass in 0xffff or the wildcard constants as a wildcard for class, subclass, protocol, vendor, and/or product. Pass in kNotifyAnyEvent (0xff) in the usbDeviceNotification field to be notified for any change that occurs.



 
void USBInstallDeviceNotification(

                     USBDeviceNotificationParameterBlock *pb);

pb: A pointer to the USBDeviceNotificationParameterBlock defined in Device Notification Parameter Block .

If a code fragment installs a device notification routine, the device notification routine must be removed with the USBRemoveDeviceNotification function before the code fragment is unloaded.

Removing The Device Callback Request

The USBRemoveDeviceNotification function removes a previously installed device notification routine.



 
OSStatus USBRemoveDeviceNotification (UInt32 token);

token: Notification identifier from the previously installed device notification routine.